Documentation/user-review-ui.txt

= Review UI

Reviewing changes is an important task and the Gerrit Web UI provides
many functionalities to make the review process comfortable and
efficient. This is a guide through the review UI that explains the
different functions and UI elements.

[[change-screen]]
== Change Screen

The change screen shows the details of a single change and provides
various actions on it.

image::images/user-review-ui-change-screen.png[width=800, link="images/user-review-ui-change-screen.png"]

[[commit-message]]
=== Commit Message Block

The focus of the change screen is on the commit message since this is
the most important information about a change. The numeric change ID
and the change status are displayed right above the commit message.

image::images/user-review-ui-change-screen-commit-message.png[width=800, link="images/user-review-ui-change-screen-commit-message.png"]

The commit message can be edited directly in the Web UI by clicking on
the `Edit Message` button in the change header. This opens a drop-down
editor box in which the commit message can be edited. Saving
modifications of the commit message automatically creates a new patch
set for the change. The commit message may only be edited on the
current patch set.

image::images/user-review-ui-change-screen-edit-commit-message.png[width=800, link="images/user-review-ui-change-screen-edit-commit-message.png"]

The numeric change ID is a link to the change and clicking on it
refreshes the change screen. By copying the link location you can get
the permalink of the change.

image::images/user-review-ui-change-screen-permalink.png[width=800, link="images/user-review-ui-change-screen-permalink.png"]

The change status shows the state of the change:

- `Needs <label>`:
+
The change is in review and an approval on the shown label is still
required to make the change submittable.

- `Not <label>`:
+
The change is in review and a veto vote on the shown label is
preventing the submit.

[[not-current]]
- `Not Current`:
+
The currently viewed patch set is outdated.
+
Please note that some operations, like voting, are not available on
outdated patch sets, but only on the current patch set.

- `Ready to Submit`:
+
The change has all necessary approvals and may be submitted.

- `Submitted, Merge Pending`:
+
The change was submitted and was added to the merge queue.
+
The change stays in the merge queue if it depends on a change that is
still in review. In this case it will get automatically merged when all
predecessor changes have been merged.
+
This status can also mean that the change depends on an abandoned
change or on an outdated patch set of another change. In this case you
may want to rebase the change.

- `Merged`:
+
The change was successfully merged into the destination branch.

- `Abandoned`:
+
The change was abandoned.

- `Draft`:
+
The change is a draft that is only visible to the change owner, the
reviewers that were explicitly added to the change, and users who have
the link:access-control.html#category_view_drafts[View Drafts] global
capability assigned.

[[commit-info]]
=== Commit Info Block

The commit info block shows information about the commit of the
currently viewed patch set.

It displays the author and the committer as links to a list of this
person's changes that have the same status as the currently viewed
change.

The commit ID and the link:user-changeid.html[Change-Id] are both
displayed with a copy-to-clipboard icon that allows the ID to be copied
into the clipboard.

If a Git web browser, such as GitWeb or Gitiles, is configured, there
is also a link to the commit in the Git web browser.

image::images/user-review-ui-change-screen-commit-info.png[width=800, link="images/user-review-ui-change-screen-commit-info.png"]

[[change-info]]
=== Change Info Block

The change info block contains detailed information about the change
and offers actions on the change.

image::images/user-review-ui-change-screen-change-info.png[width=800, link="images/user-review-ui-change-screen-change-info.png"]

- Change Owner:
+
The owner of the change is displayed as a link to a list of the owner's
changes that have the same status as the currently viewed change.
+
image::images/user-review-ui-change-screen-change-info-owner.png[width=800, link="images/user-review-ui-change-screen-change-info-owner.png"]

- Reviewers:
+
The reviewers of the change are displayed as chip tokens.
+
For each reviewer there is a tooltip that shows on which labels the
reviewer is allowed to vote.
+
New reviewers can be added by clicking on the `Add...` button. Typing
into the pop-up text field activates auto completion of user and group
names.
+
Reviewers can be removed from the change by clicking on the `x` icon
in the reviewer's chip token. Removing a reviewer also removes the
current votes of the reviewer. The removal of votes is recorded as a
message on the change.
+
Removing reviewers is protected by permissions:

** Users can always remove themselves.
** The change owner may remove any zero or positive score.
** Users with the link:access-control.html#category_remove_reviewer[
 Remove Reviewer] access right, the branch owner, the project owner
 and Gerrit administrators may remove anyone.

+
image::images/user-review-ui-change-screen-change-info-reviewers.png[width=800, link="images/user-review-ui-change-screen-change-info-reviewers.png"]

- Project / Branch / Topic:
+
The name of the project for which the change was done is displayed as a
link to the link:user-dashboards.html#project-default-dashboard[default
dashboard] of the project. If no default dashboard is defined, the link
opens a list of open changes on the project.
+
Clicking on the settings icon on the right side navigates to the
project administration screen.
+
The name of the destination branch is displayed as a link to a list
with all changes on this branch that have the same status as the
currently viewed change.
+
If a topic was assigned to the change it is displayed below the branch.
By clicking on the edit icon the topic can be set. This requires the
link:access-control.html#category_edit_topic_name[Edit Topic Name]
access right. To be able to set a topic on a closed change, the
`Edit Topic Name` must be assigned with the `force` flag.
+
image::images/user-review-ui-change-screen-change-info-project-branch-topic.png[width=800, link="images/user-review-ui-change-screen-change-info-project-branch-topic.png"]

- Submit Strategy:
+
The link:project-setup.html#submit_type[submit strategy] that will be
used to submit the change. The submit strategy is only displayed for
open changes.
+
image::images/user-review-ui-change-screen-change-info-submit-strategy.png[width=800, link="images/user-review-ui-change-screen-change-info-submit-strategy.png"]
+
If a change cannot be merged due to path conflicts this is highlighted
by a bold red `Cannot Merge` label.
+
image::images/user-review-ui-change-screen-change-info-cannot-merge.png[width=800, link="images/user-review-ui-change-screen-change-info-cannot-merge.png"]

- Time of Last Update:
+
image::images/user-review-ui-change-screen-change-info-last-update.png[width=800, link="images/user-review-ui-change-screen-change-info-last-update.png"]

- Actions:
+
Depending on the change state and the permissions of the user, different
actions are available on the change:

** `Merge Change`:
+
Submits the change and adds it to the merge queue. If possible the
change is merged into the destination branch.
+
The `Merge Change` button is available if the change is submittable and
the link:access-control.html#category_submit[Submit] access right is
assigned.
+
It is also possible to submit changes that have merge conflicts. This
allows to do the conflict resolution for a change series in a single
merge commit and submit the changes in reverse order.

** `Abandon`:
+
Abandons the change.
+
The `Abandon` button is only available if the change is open and the
link:access-control.html#category_abandon[Abandon] access right is
assigned.
+
When a change is abandoned, a panel appears that allows one to type a
comment message to explain why the change is being abandoned.

** `Restore`:
+
Restores the change.
+
The `Restore` button is only available if the change is abandoned and
the link:access-control.html#category_abandon[Abandon] and the
link:access-control.html#category_push[Push] access right is
assigned.
+
When a change is restored, a panel appears that allows one to type a
comment message to explain why the change is being restored.

** `Rebase`:
+
Rebases the change. The rebase is always done with content merge
enabled. If the rebase is successful a new patch set with the rebased
commit is created. If the rebase fails, there are conflicts that have
to be resolved manually.
+
If the change does not depend on another open change, it is rebased
onto the tip of the destination branch.
+
If the change depends on another open change, it is rebased onto the
current patch set of that other change.
+
The `Rebase` button is only available if the change can be rebased and
the link:access-control.html#category_rebase[Rebase] access right is
assigned. Rebasing merge commits is not supported.

** `Cherry-Pick`:
+
Allows to cherry-pick the change to another branch. The destination
branch can be selected from a dialog. Cherry-picking a change creates a
new open change on the selected destination branch.
+
It is also possible to cherry-pick a change to the same branch. This is
effectively the same as rebasing it to the current tip of the
destination branch. This can be used to remove dependencies on other
open changes.
+
Users can only cherry-pick changes to branches for which they are
allowed to upload changes for review.

** `Publish`:
+
Publishes the currently viewed draft patch set. If this is the first
patch set of a change that is published, the change will be published
as well.
+
The `Publish` button is only available if a draft patch set is viewed
and the user is the change owner or has the
link:access-control.html#category_publish_drafts[Publish Drafts] access
right assigned.

** `Delete Change` / `Delete Revision`:
+
Deletes the draft change / the currently viewed draft patch set.
+
The `Delete Change` / `Delete Revision` buttons are only available if a
draft patch set is viewed and the user is the change owner or has the
link:access-control.html#category_delete_drafts[Delete Drafts] access
right assigned.

** Further actions may be available if plugins are installed.

+
image::images/user-review-ui-change-screen-change-info-actions.png[width=800, link="images/user-review-ui-change-screen-change-info-actions.png"]

- Labels & Votes:
+
Approving votes are colored green; veto votes are colored red.
+
image::images/user-review-ui-change-screen-change-info-labels.png[width=800, link="images/user-review-ui-change-screen-change-info-labels.png"]

[[files]]
=== File List

The file list shows the files that are modified in the currently viewed
patch set.

image::images/user-review-ui-change-screen-file-list.png[width=800, link="images/user-review-ui-change-screen-file-list.png"]

The checkboxes in front of the file names allow files to be marked as reviewed.

image::images/user-review-ui-change-screen-file-list-mark-as-reviewed.png[width=800, link="images/user-review-ui-change-screen-file-list-mark-as-reviewed.png"]

The type of a file modification is indicated by the character in front
of the file name:

- 'no character' (Modified):
+
The file existed before this change and is modified.

- `A` (Added):
+
The file is newly added.

- `D` (Deleted):
+
The file is deleted.

- `R` (Renamed):
+
The file is renamed.

- `C` (Copied):
+
The file is new and is copied from an existing file.

image::images/user-review-ui-change-screen-file-list-modification-type.png[width=800, link="images/user-review-ui-change-screen-file-list-modification-type.png"]

If a file is renamed or copied, the name of the original file is
displayed in gray below the file name.

image::images/user-review-ui-change-screen-file-list-rename.png[width=800, link="images/user-review-ui-change-screen-file-list-rename.png"]

Repeating path segments are grayed out.

image::images/user-review-ui-change-screen-file-list-repeating-paths.png[width=800, link="images/user-review-ui-change-screen-file-list-repeating-paths.png"]

Inline comments on a file are shown in the `Comments` column.

Draft comments, i.e. comments that have been written by the current
user but not yet published, are highlighted in red.

New comments from other users, that were published after the current
user last reviewed this change, are highlighted in bold.

image::images/user-review-ui-change-screen-file-list-comments.png[width=800, link="images/user-review-ui-change-screen-file-list-comments.png"]

The size of the modifications in the files can be seen in the `Size`
column. The footer row shows the total size of the change.

For files, the `Size` column shows the sum of inserted and deleted
lines as one number. For the total size, inserted and deleted lines are
shown separately. In addition, the number of insertions and deletions
is shown as a bar. The size of the bar indicates the amount of changed
lines, and its coloring in green and red shows the proportion of
insertions to deletions.

The size information is useful to easily spot the files that contain
the most modifications; these files are likely to be the most relevant
files for this change. The total change size gives an estimate of how
long a review of this change may take.

image::images/user-review-ui-change-screen-file-list-size.png[width=800, link="images/user-review-ui-change-screen-file-list-size.png"]

In the header of the file list, the `Diff Against` selection can be
changed. This selection allows one to choose if the currently viewed
patch set should be compared against its base or against another patch
set of this change. The file list is updated accordingly.

The file list header also provides an `Open All` button that opens the
diff views for all files in the file list.

image::images/user-review-ui-change-screen-file-list-header.png[width=800, link="images/user-review-ui-change-screen-file-list-header.png"]

[[patch-sets]]
=== Patch Sets

The change screen only presents one patch set at a time. Which patch
set is currently viewed can be seen from the `Patch Sets` drop-down
panel in the change header. It shows the number of the currently viewed
patch set and the total number of patch sets, in the form: "current
patch set/number of patch sets".

If a non-current patch set is viewed this is indicated by the
link:#not-current[Not Current] change state. Please note that some
operations are only available on the current patch set.

image::images/user-review-ui-change-screen-patch-sets.png[width=800, link="images/user-review-ui-change-screen-patch-sets.png"]

The patch set drop-down list shows the list of patch sets and allows to
switch between them. The patch sets are sorted in descending order so
that the current patch set is always on top.

Patch sets that have unpublished draft comments are marked by a comment
icon.

Draft patch sets are marked with `DRAFT`.

image::images/user-review-ui-change-screen-patch-set-list.png[width=800, link="images/user-review-ui-change-screen-patch-set-list.png"]

[[old-change-screen]]
=== Old Change Screen

In addition to the normal change screen, this Gerrit version still
includes the old change screen that was used in earlier Gerrit
versions. Users that want to continue using the old change screen can
configure it in their preferences under
`Settings` > `Preferences` > `Change View`:

image::images/user-review-ui-change-view-preference.png[width=800, link="images/user-review-ui-change-view-preference.png"]

[WARNING]
The old change screen will be removed in a later version of Gerrit.

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------